{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "5de3857aca554401",
   "metadata": {},
   "source": [
    "# Cqlib 介绍"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6ba1f60517629756",
   "metadata": {},
   "source": [
    "Cqlib 是由中电信量子和国盾量子联合研发的量子计算软件开发工具包。Cqlib 基于国产指令集 QCIS 打造，提供了简单高效的量子编程工具。依托 “天衍”量子计算云平台和国盾量子计算云平台，为用户提供了量子计算真机接入服务和高性能模拟计算服务。"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "29c55fb98815357e",
   "metadata": {},
   "source": [
    "## 1. 安装"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "420befc2903eec2e",
   "metadata": {},
   "source": [
    "Cqlib 主要基于 Python 开发，支持 Python 3.10 及以上版本。"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cdc299d8562e2fdc",
   "metadata": {},
   "source": [
    "推荐使用 `pip` 安装。"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e5ce9aa6687ce71d",
   "metadata": {},
   "source": [
    "```\n",
    "pip install cqlib"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9c28df27",
   "metadata": {},
   "source": [
    "Cqlib 提供了基于 PyTorch 的仿真机，考虑到 PyTorch 太大，默认不安装 PyTorch。如果需要使用这个仿真机，请执行下面安装命令。\n",
    "\n",
    "```\n",
    "pip install cqlib[simple-sim]\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4614c302c5e77471",
   "metadata": {},
   "source": [
    "Cqlib 支持 Windows、macOS、Linux 操作系统。"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f019110dd839460f",
   "metadata": {},
   "source": [
    "|     | Windows | Linux | MacOS |\n",
    "|-----|---------|-------|-------|\n",
    "| x64 |    ✔    |   ✔  |     ✔  |\n",
    "|arm64|         |   ✔  |    ✔   |\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9dc8080500713026",
   "metadata": {},
   "source": [
    "## 2. 快速开始"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "30dc4ebc",
   "metadata": {},
   "source": [
    "以下为一个简单的量子电路构建与模拟示例："
   ]
  },
  {
   "cell_type": "code",
   "id": "7f0de9c2445071e7",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-06-10T01:25:30.651636Z",
     "start_time": "2025-06-10T01:25:28.006592Z"
    }
   },
   "source": [
    "from cqlib import Circuit\n",
    "from cqlib.simulator import StatevectorSimulator\n",
    "\n",
    "# 创建一个量子线路\n",
    "circuit = Circuit(2)\n",
    "\n",
    "# 对量子比特 0 施加 Hadamard 门\n",
    "circuit.h(0)\n",
    "# 对量子比特 1 施加 X 门\n",
    "circuit.x( 1)\n",
    "# 测量所有量子比特\n",
    "circuit.measure_all()\n",
    "\n",
    "# 使用状态向量仿真机\n",
    "simulator = StatevectorSimulator(circuit)\n",
    "probs = simulator.probs()\n",
    "print(f'probs: {probs}')"
   ],
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "probs: {'00': 0.0, '01': 0.0, '10': 0.4999999999999999, '11': 0.4999999999999999}\n"
     ]
    }
   ],
   "execution_count": 1
  },
  {
   "cell_type": "markdown",
   "id": "9292f90800ba00ad",
   "metadata": {},
   "source": [
    "注：Cqlib 使用小端模式，本示例中量子比特的测量顺序是 Q1 Q2，将低位比特（Q2）放在前面，高位比特（Q1）放在后面。因此输出结果的排序是 Q2 Q1。"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c0bbad21ead07cea",
   "metadata": {},
   "source": [
    "## 3. 主要模块"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c447a34c3285b629",
   "metadata": {},
   "source": [
    "Cqlib 包含从量子门构建量子线路、量子计算机拓扑结构适配、到量子计算机执行量子任务、处理任务数据等丰富的量子计算工具。"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b941561a4f8fdffe",
   "metadata": {},
   "source": [
    "### 3.1 量子门与量子线路"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f17941fd",
   "metadata": {},
   "source": [
    "Cqlib 内置丰富的基础与复合量子门，支持门级电路构建与模块化设计。"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ae5240868580533c",
   "metadata": {},
   "source": [
    "### 3.2 编译优化"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f4b6e578",
   "metadata": {},
   "source": [
    "Cqlib 支持常规电路简化、门合并、拓扑结构适配等编译优化功能。"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b59373b5c213cdf6",
   "metadata": {},
   "source": [
    "### 3.3 云平台接入"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "36347673eced39b2",
   "metadata": {},
   "source": [
    "Cqlib 原生集成天衍量子计算云平台，支持远程调用多种仿真量子计算机与多台量子真机，适用于教学实训与算法验证等多场景需求。"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c602d35d85cee04f",
   "metadata": {},
   "source": [
    "### 3.4 仿真机"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9854f33163cfb1aa",
   "metadata": {},
   "source": "Cqlib 内置两类高性能仿真机：一类基于C语言实现，适用于量子线路的快速仿真；一类基于 Torch 构建，适合需要求解梯度的模拟任务。"
  },
  {
   "cell_type": "markdown",
   "id": "3816d6c99b55ef97",
   "metadata": {},
   "source": [
    "### 3.5 其它工具"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fac5700fa13c67d8",
   "metadata": {},
   "source": "Cqlib 还提供了量子线路分析和数据可视化工具，兼容 QCIS/OpenQASM2.0 等格式。"
  },
  {
   "cell_type": "markdown",
   "id": "b4ed2aec35f24c40",
   "metadata": {},
   "source": [
    "## 4. 交流与反馈"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c6517f2e6d6b70af",
   "metadata": {},
   "source": [
    "Cqlib 是开源软件，欢迎用户参与社区建设。\n",
    "\n",
    "[![star](https://gitee.com/cq-lib/cqlib/badge/star.svg?theme=white)](https://gitee.com/cq-lib/cqlib/stargazers)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "78425cfa03c54d13",
   "metadata": {},
   "source": [
    "```\n",
    "gitee.com/cq-lib/cqlib\n",
    "```\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "16f686bd",
   "metadata": {},
   "source": [
    "## 5. 在线编辑器"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bfda0d97",
   "metadata": {},
   "source": [
    "天衍量子计算云平台提供了在线编程环境。支持交互式集成开发工具 Jupyter 和 VS Code，并且已预集成 Python 3.12 和 Cqlib，开发者可选择环境进行编程体验，开启量子编程之旅。\n",
    "\n",
    "\n",
    "1. 使用 Jupyter 在线编程\n",
    "\n",
    "<img src='./images/jupyter-online.png' width='800px'>\n",
    "\n",
    "2. 使用终端运行程序\n",
    "\n",
    "<img src='./images/term-online.png' width='800px'>"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": ".venv",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.11.9"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}
